# Solution: Game Contract and Canonical State Boundary

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

Use a cross-study executable contract suite against the shared AI-GM vertical
slice. This study owns the Game Contract boundary cases and acceptance evidence;
it does not duplicate the shared contracts, fixture, validator, engine, event
log, state, projection or orchestrator.

The tested authority rule is narrow: untrusted commands and generative outputs
may propose data, but only validated shared engine/event/state paths determine
canonical state. Participant views are derived from explicit visibility data.

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

```text
shared JSON fixture
-> loadFixtureBundle
-> validateBundle

untrusted proposal
-> schema validation
-> authorization/rules
-> authoritative event/state transition
-> visibility-filtered projection
-> narration without state/event write capability
```

The executable cases exercise four boundaries:

1. `executeProposal` rejects invalid payloads before RNG, event append or state
   mutation.
2. `runTurn` treats narrator projection/output as untrusted; replaying the
   stored event remains the authoritative state source.
3. `validateBundle` accepts the supported `1.0.0` fixture and returns structured
   errors for missing, ill-typed and unsupported contract/state versions.
4. `projectState` produces explicit participant allow-lists for player, GM,
   branch, party and public facts.

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

- [`prototype/game-contract.verification.test.ts`](prototype/game-contract.verification.test.ts)
  — five executable behavior tests for AC-01–AC-04.
- [`../2026-07-25-ai-gm-vertical-slice/prototype/src/`](../2026-07-25-ai-gm-vertical-slice/prototype/src/)
  — imported shared public implementation.
- [`../2026-07-25-ai-gm-vertical-slice/prototype/src/fixtures.ts`](../2026-07-25-ai-gm-vertical-slice/prototype/src/fixtures.ts)
  — authoritative `loadFixtureBundle()` loader.
- [`../2026-07-25-ai-gm-vertical-slice/prototype/fixtures/game-contract.json`](../2026-07-25-ai-gm-vertical-slice/prototype/fixtures/game-contract.json)
  — authoritative Game Contract and rules profile.

No study-local copy of the Game Contract or shared state implementation exists.

## Требования

- Verified OS/hardware: macOS 26.4 (`25E246`), arm64.
- Verified runtime: Node.js `v24.14.0`, whose built-in TypeScript strip mode
  runs these erasable `.ts` files without an experimental flag.
- Root compiler dependency: TypeScript `7.0.2`.
- Package manager declared by the root project: npm `11.9.0`.
- External services: `none`.

These are reproduction conditions for the prototype, not a production runtime
decision.

## Установка

From the repository root:

```bash
npm ci
```

The behavior suite itself uses Node’s built-in test runner and the dependencies
already declared in the root lockfile. There is no study-local install step.

## Запуск

From the repository root:

```bash
node --test RnD/technical/2026-07-25-game-contract-canonical-state/prototype/game-contract.verification.test.ts
```

Equivalent command from this study directory:

```bash
node --test prototype/game-contract.verification.test.ts
```

Expected result in the recorded environment: `5` tests, `5` pass, `0` fail,
`0` skipped and `0` TODO.

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

Run the study behavior suite, then the root strict compiler:

```bash
node --test RnD/technical/2026-07-25-game-contract-canonical-state/prototype/game-contract.verification.test.ts
npm run typecheck
```

Both commands passed in the final recorded run.

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

No environment variables, network calls or external services are used.
Synthetic inputs come from the shared vertical-slice fixture directory. The
Game Contract fixture declares:

- `contractVersion: "1.0.0"`;
- `stateVersion: "1.0.0"`;
- `migrations.supportedStateVersions: ["1.0.0"]`;
- `migrations.unknownVersion: "reject"`.

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

- The suite uses deterministic test RNG and an in-memory event log; it does not
  test production entropy, durable storage or concurrent processes.
- The malicious narrator returns an extra `statePatch` through an inferred
  structural value so TypeScript compilation succeeds while the runtime
  boundary still receives the forbidden field.
- Current tests prove canonical state/projection behavior at the shared public
  boundary, not end-to-end filtering in future UI, retrieval, summary, TTS or
  image adapters.
- Fixtures are synthetic and contain no player data or secrets.

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

- Preserve schema validation and supported-version rejection before any state
  service call.
- Keep state/event write capabilities out of parser, narrator and media
  adapters.
- Replace in-memory persistence only behind the same authoritative event/state
  contract and add concurrent-writer tests.
- Run this suite whenever shared contracts, validators, engine, state,
  projection or orchestrator change.
- Add authorization, observability, migration and downstream privacy reviews
  before production use.