# Research: Event Log, Checkpoints, Memory and Deterministic Replay

## Baseline

Canonical product sources require append-only events, replayable materialized
state, visibility-safe memory and a thousand-event gate. At study creation the
owned prototype contained only TODO ports. The shared vertical slice later
provided an in-memory event log, deterministic reducer/hash, checkpoint
functions, projection and a seeded 1,000-event runner.

The study tests those public APIs directly. It does not infer persistence or
memory behavior from source shape alone.

## Метод

1. Execute accepted commands through the shared engine and store their emitted
   events in `InMemoryEventLog`.
2. Mutate returned clones and attempt a duplicate append; compare the canonical
   stored bytes and size.
3. Replay all events from genesis and compare the complete state plus state hash
   with live materialization.
4. Checkpoint the event prefix, tamper sequence, hash and state independently,
   then exercise both verification and the authoritative replay entry point.
5. Give Pax a different branch in an isolated bundle, apply branch visibility
   to a known fact, and compare Juno/Mara/Pax projections across live, full and
   checkpoint replay.
6. Run the shared fixed-seed 1,000-event fixture and record event count, hashes,
   checkpoint evidence, privacy result and durations without setting a latency
   threshold.
7. Compare the executable surface with the original correction and
   primary-event-reference requirements; mark missing portions rather than
   claiming them.

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

| ID | Тип | Описание | Источник, путь или команда | Дата или версия |
|---|---|---|---|---|
| E-001 | Fact | MVP scope includes append-only event log, materialized state, entity facts, summaries, checkpoints and branch-aware memory | [`../../docs/prd/2026-07-22-global-party-ai-rpg.md`](../../docs/prd/2026-07-22-global-party-ai-rpg.md) | PRD Draft, 2026-07-22 |
| E-002 | Fact | FR-07 requires state/chronology replay; FR-10 forbids cross-branch leakage | [`../../docs/prd/2026-07-22-global-party-ai-rpg.md`](../../docs/prd/2026-07-22-global-party-ai-rpg.md) | PRD Draft, 2026-07-22 |
| E-003 | Fact | Guardrails require zero critical replay defects and zero branch privacy leaks | [`../../docs/prd/2026-07-22-global-party-ai-rpg.md`](../../docs/prd/2026-07-22-global-party-ai-rpg.md) | PRD Draft, 2026-07-22 |
| E-004 | Fact | Corrections must append author, reason and corrected-event reference instead of rewriting history | [`../../research/06-product-mvp-and-ai-gm.md`](../../research/06-product-mvp-and-ai-gm.md) | 2026-07-21 research pack |
| E-005 | Fact | Long-memory test requires hundreds/thousands of events, branch chronology, primary-event references and private-scope checks | [`../../research/06-product-mvp-and-ai-gm.md`](../../research/06-product-mvp-and-ai-gm.md) | 2026-07-21 research pack |
| E-006 | Fact | Thousand-event replay is a campaign-expansion gate | [`../../docs/prd/2026-07-22-global-party-ai-rpg-evidence.md`](../../docs/prd/2026-07-22-global-party-ai-rpg-evidence.md) | 2026-07-22 |
| E-007 | Implementation | Shared event log clones on append/read, enforces sequence/version/idempotency, verifies checkpoints and rejects unverified checkpoint replay | [`../2026-07-25-ai-gm-vertical-slice/prototype/src/event-log.ts`](../2026-07-25-ai-gm-vertical-slice/prototype/src/event-log.ts) | Local shared slice, 2026-07-25 |
| E-008 | Implementation | Shared long-session runner uses seed `20260725`, 1,000 deterministic proposals, checkpoint-at-half and actor projection check | [`../2026-07-25-ai-gm-vertical-slice/prototype/src/long-session.ts`](../2026-07-25-ai-gm-vertical-slice/prototype/src/long-session.ts) | Local shared slice, 2026-07-25 |
| E-009 | Measurement | Owned tests: 5 pass, 0 fail, 0 TODO; root TypeScript check passes | `node --test RnD/technical/2026-07-25-event-log-memory-replay/prototype/event-log.verification.test.ts`; `npm run typecheck` | Node v24.14.0, 2026-07-25 |
| E-010 | Measurement | 1,000 events; final/full/checkpoint hash `bff5…a5a1e`; checkpoint sequence/state version 500; verified `true`; leakage `false`; isolated durations 61.444584 ms full and 60.315583 ms checkpoint | Test diagnostic from E-009 | One isolated local run, 2026-07-25 |
| E-011 | Gap | Shared `GameEvent` has no correction event or author/reason/corrected-event reference; long fixture has no branch chronology or primary-event-reference model | [`../2026-07-25-ai-gm-vertical-slice/prototype/src/contracts.ts`](../2026-07-25-ai-gm-vertical-slice/prototype/src/contracts.ts), E-008 | Local shared slice, 2026-07-25 |

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

| Время | Изменение или попытка | Наблюдение | Artifact или evidence ID | Вывод |
|---|---|---|---|---|
| 2026-07-25T01:04:02+07:00 | Registered AC-01–AC-05 as TODO ports | Only manifest integrity executed | Original test history | No behavioral claim was justified |
| 2026-07-25 | Replaced TODOs with shared imports and live/replay/checkpoint tests | Append immutability, genesis replay and visibility checks passed | E-007, E-009 | Shared slice covers the core replay path |
| 2026-07-25 | Exercised a tampered checkpoint through the then-public replay helper | Verification returned false, but direct checkpoint replay still accepted state | Test iteration before shared fix | Verification had to be enforced at the authority boundary |
| 2026-07-25 | Shared replay entry point changed to accept genesis state, all events and checkpoint | Valid replay passes; tampered sequence/hash/state each throw `checkpoint verification failed` | E-007, E-009 | AC-03 now passes |
| 2026-07-25 | Ran isolated 1,000-event case | All three hashes equal; checkpoint 500 verified; leakage false; durations emitted | E-010 | Deterministic/hash portion of long gate passes |
| 2026-07-25 | Audited correction/long-memory fields | Correction metadata and primary-event-reference fixture are absent | E-004, E-005, E-011 | AC-01 and AC-05 remain partial |

## Выводы

- **Fact:** replaying the accepted event sequence reproduces the complete live
  state and state hash. Основание: `E-007`, `E-009`.
- **Fact:** the checkpoint authority boundary now rejects tampered sequence,
  hash and state before replay. Основание: `E-007`, `E-009`.
- **Fact:** actor fact allow-lists, including an adversarial branch split,
  remain identical across live/full/checkpoint materializations. Основание:
  `E-009`.
- **Fact:** the fixed 1,000-event hash/checkpoint/privacy run passes with the
  recorded measurement. Основание: `E-008`–`E-010`.
- **Fact:** correction metadata and primary-event-reference coverage are still
  absent. Основание: `E-004`, `E-005`, `E-011`.
- **Inference:** persistent storage can reuse these reducer/checkpoint invariants,
  but persistence durability itself is untested.

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

| Подход | Что проверили | Почему не выбран | Evidence |
|---|---|---|---|
| Mutable current-state rows as only history | Compared with replay/correction requirements | Cannot reproduce chronology or retain audit history | `E-001`–`E-004` |
| Editable summary as canonical memory | Compared with event/replay layers | Summary is lossy and generative | `E-004`, `E-005` |
| Caller optionally invokes checkpoint verification | Adversarial direct-replay iteration | A caller could accidentally authorize a corrupt checkpoint | Experiment log, `E-007` |
| Invent a replay latency gate after timing | Measured two local replay paths | One-machine timing does not define product SLO | `E-010` |
| Mark all ACs pass because five tests are green | Compared tests with exact criteria wording | Green tests cover only implemented portions; correction/reference requirements remain | `E-004`, `E-005`, `E-011` |

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

- Persistent-store durability, backup/restore and concurrent append behavior.
- Cross-runtime canonical serialization/hash equivalence.
- Correction-event semantics and authorization policy.
- Checkpoint interval/retention under realistic storage.
- Retrieval recall and summary rebuilding over long sessions.
- Latency/SLO threshold; the current duration is measurement only.