PersonalBlog/docs/adr/ADR-003-typescript-6-0-3.md

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.