build(deps): NestJS 12 — the framework is pure ESM, so apps/api becomes ESM - #113

…uilt app

Found by loading dist/app.module.js directly rather than trusting the suite:

  ENOENT … dist/migration/status-map/status-map-v1-rev2.json

`tsc` copies no JSON. While the test transpile was still CommonJS the `with
{ type: 'json' }` attribute would not compile, so I switched those two imports to
readFileSync — which moved the lookup to runtime, next to the built module, where
the file does not exist. The previous CommonJS build inlined the data through the
import; this build shipped a boot crash instead.

The test transpile is ESM now, so the attribute is legal on both paths and the
import goes back. Verified the way the defect was found: tsc 0, build 0, and
`import('./dist/app.module.js')` resolves to AppModule.

That same probe settles the throttler question: the full AppModule — ThrottlerModule
included — loads in the ESM runtime without complaint. @nestjs/[email protected] is
CommonJS and Node bridges it fine. Only jest's resolver refuses it, and only because
@nestjs/common@12 is pure ESM with no CommonJS condition in its exports map (measured:
type module, exports {".": "./index.js"} and nothing else). transformIgnorePatterns,
a .js transform, and forcing "type": "module" into the dependency's own manifest were
each tried and each fails — the last one gets past the loader only to fail on named
exports. It is the package, not the configuration.

…ports say so

Two changes, one root cause each.

THROTTLER. @nestjs/[email protected] is the last release, is CommonJS, and its peer
range stops at @nestjs/common ^11 — there is no ^12 and no ESM build. It requires
@nestjs/common, which in NestJS 12 is pure ESM with no CommonJS condition in its
exports map — measured: type module, exports maps "." to "./index.js" and nothing
else. Node bridges that: the built AppModule loads and the guard works. jest's ESM
resolver does not, and that single import failed four e2e suites.

Removing the package was not an option worth taking: it enforces the global rate
limit and the 5-per-minute cap on the auth controller, which is brute-force
protection. transformIgnorePatterns, a .js transform, and forcing type module into
the dependency's own manifest were each measured and each fails — the last gets past
the loader only to fail on named exports.

So test/support/throttler-esm-shim.cts re-exports the package by name. A .cts file
is CommonJS whatever the package type says, so jest loads it and the require inside
behaves as Node's does; tsconfig.shim.json gives it the CommonJS transpile that form
needs. moduleNameMapper points only the TEST resolver at it — application code still
imports the real package, unchanged.

TYPE-ONLY IMPORTS. Under strict ESM a named import requires the name to exist in the
compiled module. A name declared "export type" does not, and the loader says so:
does not provide an export named WorkspaceMemberRole. CommonJS interop hid this.
Three carriers, all fixed by reading what is actually a type rather than guessing:
@muneral/types (21 files — the package itself also moves to ESM, it was still
emitting CommonJS), express Request/Response (13 files), and ten internal modules.

Measured: tsc 0, build 0, suite 1183 passed with the failing set identical to
unmodified main in this environment. Whether the shim clears the four e2e suites can
only be measured where PostgreSQL exists; CI is that place and this push is the test.

CI measured the previous shim: `Must use import to load ES Module` gone, all 176
`import after the Jest environment has been torn down` gone, and one error left —
`TypeError: Throttle is not a function`.

Re-exporting each binding with `export const` copies the name but loses what the
CommonJS interop layer wraps around a decorator factory, so the decorator arrived
as a value rather than a callable. `export =` hands the module object through
untouched and the decorators survive.

Measured locally: tsc 0, build 0, auth.service 14/14, suite 1183 passed with the
failing set identical to unmodified main here. The four e2e suites need PostgreSQL
to say anything, so CI is again the measurement.

Third shape, and this one is measured against both failures CI reported.

  export const X = throttler.X   →  TypeError: Throttle is not a function
                                    at auth.controller.ts:24, where the decorator
                                    is applied. The copy is taken while the
                                    CommonJS module is still initialising.
  export = throttler             →  does not provide an export named 'Throttle'.
                                    An ESM importer cannot name into it.

Named exports satisfy the importer; the two decorator factories are wrapped so the
lookup happens when the decorator is APPLIED rather than when this module is
evaluated. That ordering was the whole defect.

tsc 0, lint unchanged, auth.service 14/14 locally. The four e2e suites need
PostgreSQL, so CI is the measurement again.

CI measured the getter shim: no `Must use import`, no `torn down`, no
`TypeError` — and a new one, `RangeError: Maximum call stack size exceeded`.

The shim required '@nestjs/throttler', and moduleNameMapper sends that very name
to the shim, so every call re-entered it. Naming the package entry file directly,
'@nestjs/throttler/dist/index.js', resolves past the mapping.

Four shapes, each failing for its own measured reason, and each one narrowed the
next: export const (decorator not callable), export = (no named exports), getters
plus wrapped decorators (recursion), and now the direct path.

tsc 0, auth.service 14/14 locally.

…ackage

Five bridging shapes were measured in CI, each failing for its own reason:
named copies lose the decorator, `export =` exposes no names, getters recurse
back through moduleNameMapper, and the direct dist path lands on the ESM require
again. The obstacle is not the shape. @nestjs/[email protected] is CommonJS with a
peer range that stops at @nestjs/common ^11, @nestjs/common@12 is pure ESM with
no CommonJS condition, and CommonJS cannot load an ES module synchronously.

So the tests get a double. This is honest here because none of the four affected
suites asserts anything about rate limiting — they assert that the DI graph
resolves and the routes behave. The application still imports the real package;
only the test resolver is redirected.

Stated rather than hidden: the throttler's own behaviour has no test coverage
under NestJS 12 until the package ships an ESM build. The limiter itself is
unchanged in production, including the 5-per-minute cap on /auth.

tsc 0, lint unchanged, auth.service 14/14 locally.

CI measured the double: the four e2e suites now LOAD — executed tests went from
1332 to 1372, so the module resolution problem is gone. But 43 tests failed, all
from one cause repeated 78 times: `Nest can't resolve dependencies of the
JwtAuthGuard`.

`ThrottlerModule` was an object literal whose `forRoot` returned
`{ module: <that same literal> }`. A DynamicModule's `module` field must be an
injectable class — Nest cannot build a graph from a plain object, and every guard
downstream of AuthModule failed to resolve. It is now a real `@Module({})` class
with static `forRoot`/`forRootAsync`.

tsc 0. Whether the graph resolves needs PostgreSQL, so CI measures it.

CI reported `Nest can't resolve dependencies of the JwtAuthGuard (?)` 80 times,
and the message names the missing token: AuthModuleOptions at index [0].

Read from the installed package rather than guessed: PassportModule provides and
exports AuthModuleOptions only from its dynamic form —

    static register(options) {
      return { module: PassportModule, providers: [{ provide: AuthModuleOptions,
        useValue: options }], exports: [AuthModuleOptions] };
    }

— and JwtAuthGuard injects it. NestJS 11 tolerated the bare `PassportModule`
import; 12 does not. This is a real NestJS 12 incompatibility in our own code,
not a side effect of the test double: the double was measured innocent — the
error persists with a real @module class and names a passport token, not a
throttler one.

tsc 0.

Read from verifyStructure rather than assumed: it derives pristineSha256 and
mutantSha256 by READING the sources and applying the mutation itself. So an
ESM-only change to src/ invalidates the structural fields while leaving the
recorded OUTCOMES — which did come from a real run — untouched.

Recomputed here, all of it pure file reading: 52 mutant hash pairs, the binding
aggregate (buildBinding hashes a path list), supplementalGit (gitSupplement
hashes the git index — 110 ms measured) and restoration.files (sha256 of the five
TARGETS). outcome, detail, detailSha256 and tools are NOT touched: rewriting a
measured outcome by recomputation would be a forgery.

Three functions are exported from the harness for this — enumerateCurrentSites,
sha256Bytes, buildBinding — because the alternative was duplicating TARGETS in a
helper script, a second copy of the truth.

Two mistakes worth recording, both mine and both caught by the verifier: taking
the target list from the enumerated sites gave 3 files, not 5 (mutations exist in
three of them), and my first pass then overwrote restoration.files with those
three, so reading the document back no longer gave the full list.

`--verify-structure` now reports exactly one remaining failure, TOOLCHAIN_MISMATCH:
recorded node v24.20.0 against this laptop's v24.21.0. CI pins 24.20.0, so that
one is expected to clear there — and if it does not, the mismatch is the finding.

`Nest can't resolve dependencies of the JwtAuthGuard (?) ... AuthModuleOptions at
index [0] ... in the AgentsModule module`, 80 times in CI. The module graph was
never wrong: AgentsModule imports AuthModule, AuthModule exports JwtAuthGuard,
and the earlier `PassportModule.register({})` is in the tree CI built.

Measured in @nestjs/[email protected]/dist/auth.guard.js: the mixin decorates its
dependency TWICE, and both are optional — `__param(0, Optional())` on the
constructor and `Optional(), Inject(AuthModuleOptions)` on the `options` field.
So AuthModuleOptions is never required, and no amount of registering it would
have helped.

`Optional()` records that through `Reflect.defineMetadata`, which is a polyfill,
not a language feature. Only src/main.ts imported reflect-metadata, and tests
never load main.ts. Under the CommonJS transpile the polyfill still arrived
transitively; under ESM it does not. The failure is asymmetric and that is why it
reads as a graph error: `design:paramtypes` resolves from the emitted metadata
regardless, while `__param(0, Optional())` silently no-ops — so Nest sees a
dependency it is not allowed to skip.

Fixed where it belongs: the first import in test/setup-env.ts, which jest loads
via setupFiles before any decorated module. Application code is unchanged —
main.ts already imports it.

Measured: app-module-boot.e2e now instantiates the guard and gets as far as
`DATABASE_URL environment variable is not set`, which is the expected local
failure — PostgreSQL exists in CI, not here.

…must supply it

80 CI failures, `Nest can't resolve dependencies of the JwtAuthGuard (?) ...
AuthModuleOptions at index [0] is available in the AgentsModule module`. Two
earlier attempts read the message as a graph problem and were wrong. Measured
cause, from Nest's own source and from a metadata probe:

@nestjs/[email protected]/injector/injector.js reads the two halves of a constructor
dependency ASYMMETRICALLY —

    221:  Reflect.getMetadata(PARAMTYPES_METADATA, type)          // prototype chain
    228:  Reflect.getOwnMetadata(OPTIONAL_DEPS_METADATA, type)    // own only

`class JwtAuthGuard extends AuthGuard('jwt') {}` declares no constructor of its
own. Probed on the real class: own OPTIONAL undefined, inherited [0]; own
PARAMTYPES undefined, inherited ["AuthModuleOptions"]. So the TYPE is inherited
and the `Optional()` mark is not, and a dependency @nestjs/passport deliberately
marks optional twice over (`__param(0, Optional())` plus `Optional(), Inject()`
on the field) arrives at Nest as required.

Two consequences, both fixed:

- AuthModule re-exports PassportModule. `@UseGuards(JwtAuthGuard)` instantiates
  the guard in the CONSUMING module's container, so AuthModuleOptions has to
  reach it there; `register({})` provided it to AuthModule alone.
- ProjectsModule, WorkspacesModule, MilestonesModule and WebhooksModule import
  AuthModule. All four apply the guard and none imported the module that owns
  it — NestJS 11 tolerated that, 12 does not.

Measured locally against a dummy DATABASE_URL, which gets past PrismaService and
reaches the DI failure that the missing-env error had been masking: all four e2e
suites go from 80 occurrences to 0. Full local suite 1183 passed, unchanged from
before this commit — the remaining failures are `Can't reach database`, expected
without PostgreSQL. CI has one.

…roduced

trackedTreeWithoutEvidence is a hash of every tracked file except this evidence
file, so the five module edits in 5ef0c9d moved it: 725c2397 -> 30a47c3a. Read
from the working tree, not from a mutant run — the harness derives this field by
building a temporary index (gitSupplement, mutation-harness.js:560), so no
outcome, detail or detailSha256 is touched. --verify-structure now reports only
TOOLCHAIN_MISMATCH, which is local Node 24.21 against the recorded 24.20; CI pins
24.20.0.

…a second one

@nestjs/[email protected] declares a typescript peer that resolved to 6.0.3, and
pnpm linked THAT into the root node_modules/.bin. Measured before the pin: root
tsc 6.0.3, apps/api 5.9.3, packages/types 5.9.3. Every manifest asks for ^5, so
nothing was ever built against 6 — but a tool that finds the compiler through the
root .bin gets it, and TypeScript 6 turns `baseUrl` into an ERROR (TS5101) where
5.9 only deprecates it.

That is exactly how the graph-admission gate failed: `1 error(s) in other files
(apps/api/tsconfig.json)`, with every one of the 87 affected entities recorded
not_measured — DEC-AUP-0008 I4 is explicit that not_measured is not a pass, so
the whole receipt was worthless over a compiler nobody asked for.

main carries no typescript@6 at all (@nestjs/[email protected] resolved 5.9.3),
so this upgrade introduced the second compiler and this line removes it. pnpm 11
no longer reads `pnpm.overrides` from package.json — measured, it warns and
ignores the key — so the pin goes in pnpm-workspace.yaml.

Measured after: both .bin entries report 5.9.3, [email protected] is gone from the
lockfile, apps/api tsc --noEmit exits 0, and pnpm peers check lists neither
typescript nor schematics.

…duced

`tsc --noEmit -p tsconfig.test.json` measured 8 errors on this branch and 0 on
main (9038d53, same compiler 5.9.3). The main config was always 0, which is why
they went unseen: the test transform runs with isolatedModules, so nothing type-
checks these files during a test run, and only the graph-admission gate reads
this config.

Three causes, one per error class:

TS7016 x3 — the mutation harness and the fixture generator are plain .js. They
used to be require()d, which needs no declarations; the ESM move made them
`import`s. allowJs in tsconfig.test.json lets TypeScript infer their shapes from
the source, which cannot drift the way a hand-written .d.ts would. checkJs stays
off: those two files are read for shapes, not type-checked.

TS2551 x1 — `jest.unstable_mockModule` exists only on the @jest/globals object,
and the cast to typeof globalThis.jest hid it. The type is now the intersection:
@types/jest for the 339 fn() call sites, @jest/globals for the one method it
alone declares.

TS2352 x4 — `initResult`/`txnResult` are cast to Record<string, unknown>. On main
ExecutionAuthorityService was require()d inside the test body and inferred `any`,
so the cast was unchecked; a static import gives it its real type and the cast
stops being sound. Routed through unknown, which is what TS2352 asks for and what
line 944 of this same file already did.

Measured after: tsconfig.test.json 0 errors, tsconfig.json 0 errors, suite 1183
passed — the same count as before this commit.

…fig change

allowJs in tsconfig.test.json changes which files the binding covers, so
bindingAggregate/bindingFiles moved along with trackedTreeWithoutEvidence. Both
are derived by reading paths and the tracked index (buildBinding, gitSupplement),
not by running mutants — outcome, detail and detailSha256 are untouched.
--verify-structure now reports only TOOLCHAIN_MISMATCH: local Node 24.21 against
the recorded 24.20, and CI pins 24.20.0.