# Strict TypeScript on Node 24 with a Bun runtime smoke lane

- **Status:** `complete`
- **Outcome:** `pass`
- **Started:** 2026-07-25
- **Updated:** 2026-07-25
- **Research ID:** `2026-07-25-typescript-runtime-toolchain`

## Проверяемый вопрос

Можно ли исполнять прототип как strict TypeScript напрямую на Node.js 24,
сохранив совместимость запуска с Bun и ровно один lockfile пакетного менеджера?

## Почему решение нужно сейчас

От выбора runtime и package-manager policy зависят синтаксические ограничения
ядра, воспроизводимость установки, CI-команды и допустимые зависимости
технического прототипа AI GameMaster.

## Scope

- Прямой запуск `.ts` в Node.js 24 и Bun без build step.
- Строгая статическая проверка отдельным TypeScript compiler.
- Один корневой `package-lock.json`; npm — единственный installer.
- Актуальный decision matrix для schema validation, reducers/rules,
  property-based tests, graph tooling, event stores, LLM eval/tracing и
  structured-output/prompt-cache возможностей провайдеров.
- Локальный исполнимый verifier без сетевых и платных model calls.

## Non-goals

- Полная совместимость всех Node API и npm-пакетов с Bun.
- Выбор production event store или LLM-провайдера.
- Измерение реальной model quality, latency, token cost или cache-hit rate.
- Использование Bun как package manager.
- Транспиляция не-erasable TypeScript-конструкций.

## Критерии успеха

| ID | Обязательный критерий | Порог или ожидаемое поведение | Способ проверки |
|---|---|---|---|
| AC-01 | Strict TypeScript проверяется отдельно от runtime | TypeScript 7.0.2, `strict`, `noEmit`, `NodeNext`, `erasableSyntaxOnly`; exit 0 | local `tsc -p` |
| AC-02 | Тот же `.ts` исполняется Node 24 | Node 24.x, все metadata invariants проходят | `node verify-toolchain.ts --expect-runtime=node` |
| AC-03 | Тот же `.ts` исполняется Bun без второго lockfile | Bun обнаружен; `bun.lock`/`bun.lockb` отсутствуют после запуска | `bun run verify-toolchain.ts --expect-runtime=bun` |
| AC-04 | Зависимости воспроизводимо зафиксированы npm | `packageManager=npm@11.9.0`, lockfile v3, четыре выбранных пакета совпадают с manifest и lock | verifier |
| AC-05 | Decision matrix покрывает обязательные категории | У каждого кандидата есть версия/граница, решение и evidence | review `RESEARCH.md` |
| AC-06 | Исследование не подменяет неизвестные платными экспериментами | 0 paid calls; model-dependent метрики отмечены `Unknown` | evidence log |

Критерии после старта не менялись.

## Рабочие гипотезы

- **Hypothesis H-01:** Node 24 сможет выполнить TypeScript-файл напрямую, если
  код ограничен erasable syntax и использует ESM/NodeNext-совместимые импорты.
- **Hypothesis H-02:** Bun сможет выполнить тот же файл поверх
  `node_modules`, установленного npm, не создавая свой lockfile, если не
  запускать команды Bun package manager.
- **Hypothesis H-03:** строгая типизация остаётся отдельным обязательным gate,
  потому что runtime type stripping/transpilation не выполняет type checking.

## Материалы

- [Исследование и evidence log](RESEARCH.md)
- [Техническое решение и запуск](SOLUTION.md)
- [Проверка и итог](VALIDATION.md)
- [`prototype/`](prototype/) — metadata verifier и tests

## Итог

**Да**, при узком контракте совместимости. Подтверждённый pipeline:

1. `npm ci` — единственная установка, источник истины — `package-lock.json`.
2. `tsc --noEmit` — обязательный strict type gate.
3. Node.js 24 — основной runtime.
4. `bun run` — дополнительный runtime smoke lane; `bun install`, `bun add` и
   `bun ci` запрещены.

Общий Node gate запускается `npm run check`; обязательный companion для
заявленной Bun lane — `npm run check:bun`. Оба выполняет `npm run check:all`.

На измеренном окружении TypeScript 7.0.2 прошёл typecheck, Node.js 24.14.0 и
Bun 1.3.6 выполнили один и тот же verifier, а второй lockfile не появился
(`E-027`–`E-031`).

Локальный outcome и общий `npm run check` получены; исследование завершено.

## Ограничения

- Проверен небольшой built-in-only verifier, а не весь будущий application
  dependency graph.
- Bun сообщает собственный Node compatibility version 24.3.0; это не
  эквивалент установленному Node.js 24.14.0.
- Node игнорирует `tsconfig.json` при исполнении. Соблюдение синтаксического
  подмножества гарантируют compiler gate и code review, не runtime.
- Независимого повтора на Linux/CI не было.

## Следующее решение

Принять npm-only/Node-first policy. Добавлять Bun smoke в CI только для
реального пользовательского runtime path и отдельно проверить clean Linux
runner.