docs(adr): record TypeScript 6.0.3 language decision as ADR-003

2026-08-31 00:26:35 +00:00
parent 1fba3d9f95
commit ee0c094398
1 changed files with 86 additions and 0 deletions
@@ -0,0 +1,86 @@
 # ADR-003: TypeScript 6.0.3 language decision
 - Status: Accepted
 - Date: 2026-08-31
 - Deciders: platform stream
 - References: ADR index (section 70), Technology stack wiki (sections 5.2, 6, 7, 8), ADR-001
 ## Context
 EPPP is a modular monolith (ADR-001) written in TypeScript across every
 module boundary: `apps/`, `packages/` and `extensions/` are all compiled from
 strict TypeScript against a shared base tsconfig (E00-S01-T10). The language
 version is therefore a platform-wide decision: it fixes the type-system
 features, the compiler behaviour and the toolchain (editor, build, CI
 typecheck) every module sees.
 The workspace already pins TypeScript exactly: the root manifest declares
 `devDependencies.typescript: "6.0.3"` (a bare MAJOR.MINOR.PATCH, no semver
 range), the committed lockfile resolves exactly one `typescript@6.0.3`, and
 every workspace package resolves `Version 6.0.3` (E00-S01-T09). The
 technology stack wiki classifies TypeScript as support class C — rolling,
 exact-pinned, tested and upgraded deliberately — and pins 6.0.3 in the golden
 compatibility tuple. TypeScript 7.0 reached GA in 2026-07 without a stable
 programmatic API before 7.1, making 6.0 the bridge release.
 ## Decision
 EPPP uses **TypeScript 6.0.3** as its language and compiler, exact-pinned in
 the root manifest and the lockfile so every workspace package and every CI
 typecheck runs the identical compiler. 6.0.3 is the baseline; a formal review
 happens after TS 7.1 is stable (per the technology stack LTS strategy), and
 any move to the 7.x line is a deliberate, ADR-recorded change. The decision
 text — **TypeScript 6.0.3 pending TS7.1 ecosystem review** — matches the ADR
 index entry (ADR-003, section 70).
 ## Alternatives
 - **TypeScript 7.0 at GA (2026-07)** — rejected: it shipped without a stable
  programmatic API before 7.1, which would put the compiler toolchain on an
  unstable surface; 6.0 is the documented bridge.
 - **TypeScript 6.x floating (caret/range)** — rejected: a range could resolve
  to a different compiler than the one the golden tuple was tested with; the
  exact pin is what makes typecheck deterministic across modules and CI.
 - **TypeScript 5.x (previous major)** — rejected: it predates the 6.0 type
  system and ecosystem position the platform was bootstrapped on; staying on
  an older major only delays the bridge.
 - **TypeScript 6.0.3 exact-pinned** — chosen: the bridge release, exact-pinned
  and CI-verified, with a formal re-review once TS 7.1 stabilises the
  programmatic API.
 ## Consequences
 - Positive: one exact compiler version across apps, packages and extensions
  makes typecheck results reproducible locally and in CI; the 6.0 bridge is a
  known-good stepping stone to the 7.x line; strict mode across the workspace
  stays uniform.
 - Negative: the language feature set is fixed at 6.0.3 until the reviewed
  upgrade; any tooling that needs the 7.x programmatic API waits for the TS
  7.1 formal review.
 - Neutral: upgrades inside the pinned major remain controlled by the
  dependency sweep; the language choice is invisible to the deployed runtime
  (TypeScript compiles away) but is enforced at build and typecheck time.
 ## Operational impact
 - `pnpm install --frozen-lockfile` resolves exactly `typescript@6.0.3`; the
  lockfile contains one resolved TypeScript entry, so no package can drift
  onto another version.
 - Every workspace `build`/`typecheck` script invokes the pinned compiler
  (`pnpm exec tsc`), and the typescript-pin suite asserts each package
  resolves `Version 6.0.3`.
 - CI stage 2 (typecheck) runs `pnpm typecheck` across the workspace, so the
  language pin is continuously verified on every pull request.
 - A TypeScript upgrade is a class C lane change: patch/minor through the
  sweep with full CI; the 7.x major is a programme item with its own ADR.
 ## Revisit trigger
 - Revisit after TypeScript 7.1 is stable: the formal review (per the LTS
  strategy) decides whether the platform moves to the 7.x line, recorded as a
  new ADR.
 - Revisit if a workspace package needs a type-system feature or toolchain
  capability that 6.0.3 cannot provide, or if the ecosystem (editors, tools,
  type packages) leaves the 6.0 bridge unsupported.
 - Revisit if a module boundary contract (ADR-027 to ADR-032) becomes
  unrepresentable in the pinned type system.