# Event Log, Checkpoints, Memory and Deterministic Replay

- **Status:** `complete`
- **Outcome:** `partial`
- **Started:** 2026-07-25
- **Updated:** 2026-07-25
- **Research ID:** `2026-07-25-event-log-memory-replay`

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

Можно ли на существующем vertical slice доказать, что append-only event log и
проверяемые checkpoints детерминированно восстанавливают canonical state,
отклоняют испорченный checkpoint и сохраняют visibility scopes?

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

PRD делает replay и отсутствие state drift частью product differentiation, а
long campaigns откладывает до thousand-event proof. Поэтому event/checkpoint
граница должна быть проверена до выбора persistent storage и memory retrieval.

## Scope

- Реальное подключение к shared `InMemoryEventLog`, reducer, state hash,
  checkpoint verification, replay и participant projection.
- Append-only behavior для accepted events и защита stored events от мутаций
  потребителем.
- Genesis replay и verified-checkpoint replay.
- Tampered sequence/hash/state adversarial cases.
- Explicit player/branch visibility matrix до и после replay.
- Фиксированный 1,000-event run с seed, checkpoint, hashes и измеренным временем.
- Честная фиксация частей исходного contract, которых shared slice ещё не имеет.

## Non-goals

- Database, queue, snapshot storage, backup/restore или distributed consensus.
- Retrieval-quality/model-memory benchmark.
- Production durability, concurrency или cross-runtime hash vectors.
- Добавление correction-event или memory-summary API в shared slice.

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

| ID | Обязательный критерий | Проверка | Результат |
|---|---|---|---|
| AC-01 | History is append-only; corrections append author, reason and corrected-event reference | Stored-event clones нельзя использовать для переписывания истории; duplicate append отклоняется. Shared `GameEvent` не имеет correction event/metadata | `partial` |
| AC-02 | Genesis replay reproduces canonical state exactly | Deep equality полного `GameState` и одинаковый SHA-256 state hash для live/replay | `pass` |
| AC-03 | Checkpoint is verified, never trusted blindly | Valid checkpoint даёт live state; tampered sequence/hash/state не проходят `verifyCheckpoint`, а `replayFromCheckpoint` throws | `pass` |
| AC-04 | Visibility survives storage/checkpoint/replay | Для Juno/Mara/Pax совпадают explicit fact allow-lists; отдельная branch исключает Pax; live/full/checkpoint projections идентичны | `pass` |
| AC-05 | Fixed 1,000-event gate is executable | 1,000 events, checkpoint 500, identical hashes, no private leakage, duration emitted. Fixture не моделирует branch chronology или primary-event references | `partial` |

Performance является наблюдением, а не post-hoc gate.

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

- **H-01 подтверждена для реализованной границы:** checkpoint может оставаться
  derived cache, потому что public checkpoint replay сначала проверяет prefix.
- **H-02 подтверждена для state/fact projection:** одинаковая visibility metadata
  даёт одинаковые actor projections после full и checkpoint replay.
- **H-03 не проверена:** correction events могут сохранить audit history без
  переписывания original event; shared event contract пока их не моделирует.

## Материалы

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

## Итог

Детерминированный replay, обязательная checkpoint verification и visibility
projection доказаны на shared implementation. Изолированный 1,000-event run
получил один и тот же hash
`bff5dbc7db58b470a29b17d68ae6ac61ad89571087bf42e22f1e898b245a5a1e`
для live, genesis и checkpoint replay; checkpoint 500 verified, private leakage
`false`.

Outcome остаётся `partial`: AC-01 требует отдельного correction event с author,
reason и corrected-event reference, а полная часть AC-05 требует branch
chronology и primary-event-reference fixture.

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

- Event log находится в памяти; durability не проверена.
- Correction/memory-reference contracts отсутствуют.
- SHA-256 hash доказан только в текущем Node runtime, не cross-runtime.
- 1,000 synthetic events не доказывают product quality, retrieval recall,
  production throughput или market demand.

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

`GO` для использования verified replay boundary в следующем storage spike.
Перед заявлением полного long-campaign gate нужно добавить correction event и
long fixture с branch chronology и primary-event references. До этого
исследование остаётся `partial`, а summaries/LLM memory не могут быть authority.