RnD · Линия доказательств Technical R&D
Каталог и оглавление
TECH.IDX RnD/technical/2026-07-25-game-contract-canonical-state/README.md raw.md ->

Game Contract and Canonical State Boundary

  • Status: complete
  • Outcome: pass
  • Started: 2026-07-25
  • Updated: 2026-07-25
  • Research ID: 2026-07-25-game-contract-canonical-state

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

Можно ли выразить минимальный versioned Game Contract и canonical state boundary так, чтобы schema-invalid команды и generative output не могли изменить каноническое состояние, а каждая participant projection соблюдала visibility scope?

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

PRD делает authoritative state измеримым отличием продукта и требует, чтобы clarification, rules validation и state transition завершались до narration. Контракт нужен до production-реализации rules engine, event store и LLM adapters, иначе каждый слой сможет неявно определить собственную несовместимую форму канона.

Scope#

  • Versioned envelope для Game Contract, command proposal и canonical state.
  • Граница между недоверенным LLM proposal/narration и state service.
  • Schema validation до RNG, event append и state mutation.
  • Canonical state fields для персонажей, inventory, statuses, location, initiative, chronology, state version и event sequence.
  • Visibility scopes public, party, branch, player и GM как часть данных, а не prompt-only правило.
  • Executable contract tests against the shared vertical-slice public modules and authoritative fixture.

Non-goals#

  • Production API, database, distributed event store or deployment topology.
  • Выбор новой schema-validation библиотеки или canonical serialization format.
  • Сюжет, карта, NPC content и UI.
  • Копирование текста, контента или branded compatibility Knave/D&D.
  • Доказательство production reliability, downstream media privacy или multi-process concurrency одним локальным прогоном.

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

Критерии были зафиксированы до подключения executable shared implementation. Числовые gates взяты только из канонического PRD; остальные строки задают точное поведение без придуманного процентного порога.

ID Обязательный критерий Порог или ожидаемое поведение Способ проверки
AC-01 Schema-invalid state-changing command останавливается на boundary 100% labelled schema-invalid fixtures требуют structured rejection/clarification до RNG или commit; state hash, state version и event count не меняются Submit invalid, missing, ill-typed and forbidden-extra-field payloads through executeProposal; compare RNG calls, event count, state hash and version
AC-02 LLM не имеет mutation capability Proposal и narration adapters возвращают только typed data/text; попытка передать state patch, HP/inventory/location/status mutation или fabricated event отклоняется, canonical state остаётся byte-for-byte/hash-equivalent исходному Run a narrator that mutates its projection and returns an extra statePatch; compare canonical state with authoritative event replay
AC-03 Game Contract и state имеют явную версию и однозначную schema boundary Valid fixture проходит executable schema validator; missing, unknown-version and ill-typed fixtures return structured errors before state service Validate the shared fixture plus missing, numeric and unsupported 999.0.0 contract/state versions; inspect structured issue paths/codes
AC-04 Visibility является обязательным свойством canonical facts/projections 0 unauthorized branch facts в adversarial projections; fact outside actor scope is absent from the participant projection Build explicit allow-lists for three participants and exercise player, GM, branch and public visibility through projectState

Изменений критериев после старта не было.

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

  • Hypothesis H-01: capability boundary, в которой generative adapters не получают state write port, делает прямую LLM mutation структурно невозможной; executable mutation attempt не изменила canonical state или stored event.
  • Hypothesis H-02: visibility metadata на canonical fact/event, а не только в prompt, позволяет строить детерминированные participant projections; explicit allow-list checks прошли для всех зарегистрированных scope cases.

Материалы#

Итог#

Локальный прогон на Node.js v24.14.0 завершился 5/5 passing tests, без failures, skips или TODO. AC-01–AC-04 выполнены: invalid commands не достигли RNG/event/state, malicious narration не изменила canonical state, missing, ill-typed и unsupported versions получили structured rejection, а participant projections совпали с explicit allow-lists. Root npm run typecheck также завершился успешно. Evidence и точные команды записаны в VALIDATION.md.

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

  • Это один локальный deterministic прогон с synthetic fixtures, а не reliability или load measurement.
  • In-memory event log и current projection boundary не доказывают multi-process storage safety или отсутствие утечек в ещё не подключённых UI, retrieval, summary, TTS и image adapters.
  • Passing contract tests не выбирают production schema migration window, serialization/hash format или database.

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

GO для переноса проверенной boundary-модели в production design: сохранять shared fixture/API как единый источник истины, запрещать generative adapters state/event write capability и запускать эти contract tests при изменениях validators, orchestrator, state или projection. Production promotion отдельно требует persistent event store, authorization/threat review и downstream privacy integration tests.