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.

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

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 — five executable behavior tests for AC-01–AC-04.
• ../2026-07-25-ai-gm-vertical-slice/prototype/src/ — imported shared public implementation.
• ../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 — 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:

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:

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

Equivalent command from this study directory:

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:

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.