# Typed AI GameMaster orchestration

- **Status:** `complete`
- **Outcome:** `pass`
- **Started:** 2026-07-25
- **Updated:** 2026-07-25
- **Research ID:** `2026-07-25-ai-gm-orchestration`

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

Можно ли ограничить LLM ролями proposal/clarification/narration так, чтобы ни
один model output не мог изменить canonical state или получить чужой private
context?

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

Без исполнимой границы «model proposes, kernel commits» весь AI GameMaster
остаётся prompt-level обещанием.

## Scope

- Typed command proposal и schema validation.
- Permission/visibility projection до вызова model adapter.
- Narration только после authoritative commit.
- Fake adapters и telemetry без платных API-вызовов.

## Non-goals

- Оценка качества реальной модели.
- STT, TTS, WebRTC и production prompt engineering.
- Выбор одного LLM-провайдера.

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

| ID | Обязательный критерий | Ожидаемое поведение | Способ проверки |
|---|---|---|---|
| AC-01 | Invalid proposal не достигает reducer | Structured refusal/clarification, state hash без изменений | `npm run test:technical` |
| AC-02 | Narrator запускается только после commit | Narration содержит committed `stateVersion` | `npm run technical:demo` |
| AC-03 | Model context минимально авторизован | GM-only и чужие player/branch facts отсутствуют в projection | adversarial suite |
| AC-04 | Платный provider нельзя вызвать неявно | Default adapter полностью локальный; real adapter не реализован | source inspection + demo |

2026-07-25: root `test:technical` позже расширили тестами независимых
исследований. Для evidence этого вопроса дополнительно зафиксирован точный
central vertical-slice test glob; критерии и пороги не менялись.

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

- **Hypothesis H-01:** capability-separated adapters плюс typed kernel
  превращают prompt injection в отклонённые данные, а не в привилегированную
  инструкцию.

## Материалы

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

## Итог

**Да, в проверенном локальном scope.** Центральный orchestrator передаёт модели
только participant projection, пропускает proposal через authoritative kernel
и вызывает narrator после commit. Fresh wrapper run подтвердил:

- accepted state version `1` совпал с narration state version `1`;
- commit count = `1`, replay hash совпал;
- 16 adversarial cases дали 0 failures, 0 invalid mutations и 0 private leaks;
- adapter = `fake_local`, real provider calls = `0`, real-provider запуск
  требует отдельного explicit permission.

Evidence: `E-004`–`E-010` в `RESEARCH.md` и таблица AC в `VALIDATION.md`.
Финальный `npm run check` прошёл; status `complete`.

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

Fake adapters доказывают порядок вызовов и data boundary, но не structured
output reliability, latency, retry behavior, безопасность или качество
реального LLM.

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

Принять typed boundary как production design constraint. Provider adapter,
quality benchmark, secrets, retries и redaction оформлять отдельной задачей
только после явного разрешения на внешние вызовы.