Solution: Node-first strict TypeScript with npm-only installs

Выбранный подход#

Прототип использует Node.js 24 как основной runtime и TypeScript 7.0.2 как отдельный static gate. Bun запускает тот же source только как compatibility smoke. Корневой npm manifest и package-lock.json — единственные package metadata; отдельного manifest/lock внутри исследования намеренно нет.

Главный риск — ложное объединение трёх разных гарантий. Выбранный pipeline разделяет их:

• npm ci гарантирует lock-based install;
• tsc --noEmit гарантирует type checking;
• Node/Bun CLI run гарантирует только runtime execution данного сценария.

Обязательный toolchain contract#

1. Все установки выполняются npm ci/npm install; изменение зависимостей — только npm.
2. Не запускать bun install, bun add, bun remove, bun update или bun ci. Эти команды выходят за runtime-only lane и могут создать bun.lock.
3. Source ограничен erasable TypeScript syntax:
   • type aliases/interfaces/type annotations допустимы;
   • enums, parameter properties, runtime namespaces и другие конструкции, требующие TypeScript transform, не используются;
   • type-only imports пишутся как import type.
4. ESM relative imports содержат расширение .ts.
5. Не использовать tsconfig paths как runtime resolution contract: Node игнорирует tsconfig.json.
6. Runtime code не обращается к Bun.*; общий слой использует проверенные node: APIs или platform-neutral ECMAScript.
7. Любой provider output проходит два независимых слоя: JSON Schema/Ajv, затем authoritative domain reducer.

Архитектура и поток данных#

package.json + package-lock.json
             |
          npm ci
             |
       root node_modules
          /       \
 tsc --noEmit    runtime smoke
    strict       /           \
             Node 24       Bun 1.3
               \             /
                same .ts entry
                     |
        package/lock invariant report

Для будущего game kernel:

provider structured output
  -> JSON parse/schema constraint
  -> Ajv 8.20.0 revalidation
  -> pure typed authoritative reducer
  -> append-only event
  -> narration/projection

XState, JSON rules, graph libraries, external event stores и managed eval platforms не входят в этот minimal runtime proof.

Структура прототипа#

• prototype/tsconfig.json — strict NodeNext/erasable-syntax compiler gate.
• prototype/verify-toolchain.ts — pure evaluator + CLI inspection root manifest/lock/runtime.
• prototype/verify-toolchain.test.ts — acceptance и competing-lock regression cases.
• prototype/README.md — краткий runnable contract.

Требования#

Фактически проверенная конфигурация:

• macOS 26.4, Apple arm64;
• Node.js 24.14.0;
• npm 11.9.0;
• Bun 1.3.6 — только для optional smoke;
• TypeScript 7.0.2 и @types/node 24.13.3;
• Ajv 8.20.0 и fast-check 4.9.0 зафиксированы root lock, хотя metadata verifier намеренно не импортирует их;
• внешние сервисы и secrets: none.

Поддерживаемый вывод ограничен Node major 24 и измеренной Bun 1.3.6. Другие patch/minor версии требуют повторного запуска, а не предположения.

Установка#

Из корня репозитория:

npm ci

Не выполнять bun install: Bun использует уже установленный npm node_modules только во время runtime smoke.

Запуск#

Основной runtime:

node RnD/technical/2026-07-25-typescript-runtime-toolchain/prototype/verify-toolchain.ts --expect-runtime=node

Ожидается JSON с "ok": true, runtime node, Node major 24, npm packageManager, lockfile v3, совпадающими pins и отсутствующими Bun lockfiles.

Optional Bun smoke:

bun run RnD/technical/2026-07-25-typescript-runtime-toolchain/prototype/verify-toolchain.ts --expect-runtime=bun

Тестирование#

Из корня репозитория:

./node_modules/.bin/tsc -p RnD/technical/2026-07-25-typescript-runtime-toolchain/prototype/tsconfig.json
node --test RnD/technical/2026-07-25-typescript-runtime-toolchain/prototype/verify-toolchain.test.ts
bun test RnD/technical/2026-07-25-typescript-runtime-toolchain/prototype/verify-toolchain.test.ts

Full repository check:

npm run check
npm run check:bun
# или оба последовательно
npm run check:all

Фактический результат общего gate записан в VALIDATION.md.

Конфигурация#

Environment variables отсутствуют. CLI принимает один необязательный параметр:

• --expect-runtime=node
• --expect-runtime=bun

Без параметра verifier ожидает фактически обнаруженный runtime.

Pinned baseline находится в EXPECTED_PACKAGE_MANAGER и EXPECTED_PACKAGES. Его изменение должно идти вместе с root manifest/lock, документацией и повторной валидацией.

Ограничения и безопасность#

• Verifier только читает local JSON и проверяет наличие lockfiles; он не изменяет package metadata и не запускает installers.
• Никакие API keys не читаются, сетевые запросы и LLM calls не выполняются.
• JSON.parse обёрнут object-boundary check, но это исследовательский metadata reader, не универсальный untrusted-file parser.
• Пройденный Bun smoke не доказывает совместимость native addons, filesystem edge cases, workers, streams или будущих provider SDK.
• Provider schema-constrained output нельзя сразу commit-ить в game state: schema проверяет shape, domain reducer — допустимость действия.

Условия переноса в production#

• Выполнить npm ci && npm run check на clean Linux CI.
• Добавить Bun smoke только на реальные public entry points.
• Зафиксировать Node patch через deployment image/version manager.
• Ввести dependency compatibility inventory до обещания Bun support.
• Для event store определить idempotency, optimistic concurrency, backup, migration и replay SLO.
• Для LLM выбрать provider/data policy, затем провести versioned, budget-capped eval с raw usage и cache counters.
• Подключить OpenTelemetry/exporter только когда появится multi-process trace path; не добавлять SDK ради неиспользуемой абстракции.