# Research: integrated AI GameMaster vertical slice

## Baseline

Репозиторий был статической research library: game runtime, schemas, tests,
adapters, event log и replay отсутствовали.

## Метод

1. До production code зафиксировать contracts и RED behavioral tests.
2. Реализовать минимальный TypeScript kernel на pure data/reducers.
3. Запустить fixed demo с seeded RNG и original sci-fi comedy fixture.
4. Replay events и сравнить canonical SHA-256.
5. Запустить named adversarial corpus и fixed-seed properties.
6. Сравнить baseline/candidate context strategies на одном manifest.

## Реестр доказательств

| ID | Тип | Описание | Источник, путь или команда | Дата или версия |
|---|---|---|---|---|
| E-001 | Fact | Canonical product boundary: deterministic state, event log, split privacy, LLM narration only | `RnD/docs/prd/2026-07-22-global-party-ai-rpg.md` | 2026-07-24 |
| E-002 | Fact | Knave 1e declares CC BY 4.0 and classless/d20/equipment-led design | https://questingbeast.itch.io/knave | accessed 2026-07-25 |
| E-003 | Fact | Knave 2e permits mechanics reuse but not text/art | https://questingbeast.itch.io/knave-second-edition and published license page | accessed 2026-07-25 |
| E-004 | Fact | Node 24 executes erasable TypeScript directly; type stripping stable since 24.12 | https://nodejs.org/api/typescript.html | accessed 2026-07-25; Node 24.14.0 |
| E-005 | Measurement | Initial technical test run: 0 pass, 3 fail because prototype modules did not exist | `npm run test:technical` | 2026-07-25 |
| E-006 | Measurement | Central vertical-slice suite: 10 pass, 0 fail | `node --test RnD/technical/2026-07-25-ai-gm-vertical-slice/prototype/tests/*.test.ts` | 2026-07-25 |
| E-007 | Measurement | Expanded Technical R&D suite: 41 pass, 0 fail, 0 TODO | `npm run test:technical` | 2026-07-25 |
| E-008 | Measurement | Node demo accepted one check, committed state version 1 before narration, and produced identical live/replay hashes | `npm run technical:demo`; `artifacts/derived/demo-result.json` | 2026-07-25; seed 20260725 |
| E-009 | Measurement | Named adversarial corpus: 16 cases, 0 failures, 0 invalid transitions, 0 private leaks, 0 duplicate commits | `artifacts/derived/adversarial-report.json` | 2026-07-25 |
| E-010 | Measurement | Two fixed-seed property tests each ran 200 generated cases | `prototype/tests/property.test.ts`; `npm run test:technical` | 2026-07-25; seed 20260725 |
| E-011 | Measurement | 1,000-event live/full/checkpoint replay hashes matched; checkpoint 500 verified; private leakage false | `artifacts/derived/long-session-replay.json` | 2026-07-25 |
| E-012 | Measurement | Same-manifest local benchmark reduced synthetic input-token proxy 162,515 → 34,160 (78.9804%); provider calls 0 | `npm run technical:benchmark`; `artifacts/derived/baseline-vs-optimized.json` | 2026-07-25 |
| E-013 | Measurement | Bun 1.3.6 executed the same demo and produced the same canonical hash and adversarial result as Node | `bun run .../prototype/src/cli.ts demo` | 2026-07-25 |
| E-014 | Measurement | Clean lockfile install completed, then full repository check passed: site tests, 41 technical tests, strict typecheck, 10-study validator, 96-document build and rendered-link validation | `npm ci && npm run check` | 2026-07-25 |

## Журнал экспериментов

| Время | Изменение или попытка | Наблюдение | Artifact или evidence ID | Вывод |
|---|---|---|---|---|
| 2026-07-25T01:20:00+07:00 | RED test run | All three test files failed with `ERR_MODULE_NOT_FOUND` for missing implementation | `E-005` | Behavior not implemented; RED valid |
| 2026-07-25 | Implemented contracts, validators, reducer, RNG, event log, projections and fake adapters | Central suite 10/10 | `E-006` | H-01 supported in local prototype |
| 2026-07-25 | Added named adversarial and fixed-seed properties | 16/16 adversarial; two 200-run properties passed | `E-009`, `E-010` | Invalid model/player proposals fail before canonical mutation |
| 2026-07-25 | Replayed 1,000 events from genesis and verified checkpoint 500 | Three hashes identical; no private leak | `E-011` | Checkpoint can be derived cache only after prefix verification |
| 2026-07-25 | Compared full-context baseline with projection/delta candidate | Proxy reduction 78.9804%; model-dependent metrics remain null/not measured | `E-012` | Harness works; non-inferiority remains Unknown |
| 2026-07-25 | Executed vertical slice under Bun | Same canonical hash and 16/16 adversarial result | `E-013` | Shared source supports measured Bun runtime lane |
| 2026-07-25 | Reinstalled from npm lockfile and ran full repository gate | Both commands exited 0; tests, typecheck, study validation, build and link validation passed | `E-014` | Local clean-command contract satisfied |

## Выводы

- **Fact:** baseline had no executable kernel. Основание: `E-005`.
- **Inference:** Knave 1e is a safer mechanical reference than 2e for an
  attributed prototype, while genre-neutral contracts must remain project-owned.
  Основание: `E-002`, `E-003`.
- **Measurement:** authoritative commit preceded narration and replay reproduced
  the same canonical hash. Основание: `E-006`, `E-008`.
- **Measurement:** the original non-fantasy fixture passed schema, semantic,
  privacy and replay gates under Node and Bun. Основание: `E-008`, `E-009`,
  `E-013`.
- **Inference:** projection/delta routing is worth a real-model experiment
  because its local input-size proxy is smaller, but no cost or quality claim is
  valid yet. Основание: `E-012`.

## Рассмотренные альтернативы

| Подход | Что проверили | Почему не выбран | Evidence |
|---|---|---|---|
| Direct D&D 5e implementation | PRD/IP/scope | Too complex and explicitly out of scope | `E-001` |
| Knave 2e text/content | License boundary | Text/art not reusable; fantasy-heavy toolkit | `E-003` |
| Knave 1e verbatim product rules | Product requirement | Would couple brand/setting; use as baseline, not product identity | `E-001`, `E-002` |
| Original genre-neutral profile | Contract prototype | Candidate | `E-001`, `E-002` |

## Неизвестные

- **Unknown:** generalization from one synthetic non-fantasy fixture to arbitrary
  host-authored genres.
- **Unknown:** real LLM narration quality, structured-output reliability,
  latency, retries, tokens and cost.
- **Unknown:** production durability, multi-process concurrency, correction
  events, authentication and recovery behavior.
- **Unknown:** dedicated authoring `AdventureContract`/`MapContract` and the
  vertical slice runtime contracts are different shapes; no shared package,
  compiler/mapping or cross-contract end-to-end test exists.