crossmate

Journal.md (10580B)

---

 # Move Journal — Design
 
 A local, append-only log of every grid move, plus undo/redo built on top of it.
 Phase 1 is entirely local (Core Data only, no CloudKit). Phase 2a uploads each
 device's journal at game completion so the whole game can be replayed; it is
 **built**. Phase 2b (the replay viewer that merges all devices' journals) and
 the undo completion-lockout are still deferred — see "Remaining work" below.
 
 ## Goals
 
 1. **Undo / redo during play.** A player can walk back their own moves, with no
    fixed depth limit. Undo applies a *forward* mutation through the normal
    `GameMutator` path, so it syncs to collaborators like any other edit — it is
    not a time machine.
 2. **Replay after completion (Phase 2).** Merging every device's uploaded
    journal by timestamp reconstructs the full game, including corrections.
 
 **Every grid-changing move is recorded** (so replay is faithful), but only a
 subset is **undoable**: letter `input` (adds/single-cell deletes) and `clear`
 (the bulk clear gesture). `check` and `reveal` are recorded for replay but never
 offered as undo steps — they're help actions, not edits you rewind.
 
 ## Why a new structure (not the Moves record)
 
 `MovesValue.cells` (`Sync/Moves.swift`) is a *compacted current-state* map —
 `[GridPosition: TimestampedCell]`, only the latest touch per cell survives. It
 carries no history, so neither undo nor replay can be reconstructed from it.
 Snapshotting the whole Moves value per move is O(moves × cells) — tens of MB for
 a single game — and is also collaboratively wrong (restoring a snapshot rewrites
 every cell, clobbering peers). Instead we log **one entry per changed cell**, in
 the Moves cell shape, and recover the "before" value via a back-pointer.
 
 ## Data model — `JournalEntity`
 
 Local Core Data entity, cascade-deleted with its `GameEntity`. Append-only;
 rows are never mutated or deleted in normal operation.
 
 | Field | Type | Purpose |
 |---|---|---|
 | `gameID` | UUID | game scope |
 | `seq` | Int64 | monotonic per game; stable local ordering + undo walk |
 | `timestamp` | Date | wall-clock; Phase 2 replay ordering + cross-device merge |
 | `row`, `col` | Int16 | cell |
 | `letter` | String | **after**-state letter |
 | `markCode` | Int16 | after-state `CellMark` as one lossless code (see `CellMarkCodec.code`) |
 | `cellAuthorID` | String? | preserved letter author (mirrors `emitMove`) |
 | `actingAuthorID` | String? | iCloud user who made the move |
 | `kind` | Int16 | 0 input / 1 check / 2 reveal / 3 clear / 4 undo / 5 redo (`input` + `clear` are undoable) |
 | `targetSeq` | Int64? | for undo/redo, the entry it acts on |
 | `batchID` | UUID? | groups one gesture (bulk check/reveal/clear, or one undo/redo op) into a single undo step |
 | `prevSeqAtCell` | Int64? | seq of the previous entry at this `(row,col)`; `nil` = cell was empty before |
 
 There is **no stored before-state**. To undo entry `E`, follow `E.prevSeqAtCell`
 to one prior entry and apply *its* after-state (or empty if `nil`). O(1) keyed
 lookup, no scan; after-states stay the single source of truth and the pointer
 can never go stale because the log is immutable.
 
 Adding the entity is an additive, automatic lightweight migration. Unlike the
 synced Moves wire format (which flattens the mark into `markKind` + two check
 bools), the journal stores the whole `CellMark` as one `markCode` — the
 two-bool form is a wart we chose not to propagate into new local storage. The
 shared `CellMarkCodec` now owns both encodings.
 
 ## `MovesJournal`
 
 `@MainActor` class, a shared singleton beside `MovesUpdater`. Holds the current
 game's entries in memory (loaded lazily from Core Data on first use, so undo
 survives relaunch), persists each new entry on a background context (the
 in-memory list is authoritative for the session, so async persistence is fine).
 
 - `record(...)` — assigns `seq` (= max+1), looks up & updates a
   `[GridPosition: Int64]` last-seq map to set `prevSeqAtCell`, appends in memory,
   persists.
 - `planUndo(gameID:)` / `planRedo(gameID:)` — derive the next step and return
   per-cell restore instructions; pure, no mutation of state.
 - `canUndo` / `canRedo`.
 
 ### Undo/redo derivation
 
 One pass over the in-memory entries (seq order), grouping consecutive entries
 that share a `batchID`/kind into *operations*, then a stack machine:
 
 ```
 for op in operations:
     userEdit -> redoStack = []; liveStack.append(op)   // new edit cuts redo branch
     undo     -> if let s = liveStack.popLast() { redoStack.append(s) }
     redo     -> if let s = redoStack.popLast() { liveStack.append(s) }
 ```
 
 `liveStack.last` is the next thing to undo; `redoStack.last` the next to redo.
 Undone entries are never deleted — replay keeps the true history — the
 derivation just stops offering them once a new edit cuts the branch.
 
 ### The superseded guard
 
 Each restore instruction carries the entry's after-state as `expectedCurrent`,
 which `GameMutator` compares (by **letter only**) to the live `game` cell. If
 the letter differs, a collaborator (or a later edit) changed the cell since, so
 we **skip that cell** — this stops undo from ever clobbering someone else's
 current letter. Only the letter is compared so that a peer's check/reveal (a
 mark-only change) doesn't block undoing one's own letter. In a batch, superseded
 cells are skipped individually; the step still counts as undone.
 
 ## `GameMutator` / `Game` hooks
 
 - `emitMove` gains `journalKind` + `batchID` + `targetSeq` and, alongside the
   existing sync enqueue, calls `movesJournal.record(...)` with the after-state.
   A move is recorded only when the cell's state actually changed.
 - `setLetter`/`clearLetter` → `kind = .input`, `batchID = nil` (one step each).
   `checkCells`/`revealCells`/`clearCells` → `kind = .check`/`.reveal`/`.clear`,
   one shared `batchID`. Only `.input` and `.clear` are undoable; `.check`/
   `.reveal` are recorded for replay but inert to the stack machine.
 - `undo()` / `redo()`: ask the journal for a plan, apply surviving instructions
   via a new low-level `Game.applyCellState(...)` (sets entry + mark + author
   directly; can override the reveal lock), emitting each as `kind = .undo`/
   `.redo` under one op `batchID`.
 - `canUndo` / `canRedo` drive the UI control's enabled state.
 
 ## Open questions / notes
 
 - **Undo control UI.** Buttons in `PuzzleView` are deferred to follow-up.
 - **`recordedEntries(gameID:)`** exposes the log read-only; it's a seam Phase 2b
   replay can read locally (the cross-device merge reads uploaded assets).
 
 ## Phase 2a — journal upload (built)
 
 At game completion (win or resign, in `GameStore`), each device encodes its
 whole local `JournalEntity` log via `JournalCodec` (JSON) and pushes it as a
 `CKAsset` on a `Journal` record — one per `(game, authorID, deviceID)`, named
 `journal-<gameID>-<authorID>-<deviceID>`, written into the game's existing zone.
 It mirrors the `Moves` record path and is **write-once with no system-fields
 archive** (like `Ping`/`Decision`): `buildRecord` reconstructs the asset from the
 durable `JournalEntity` rows, so a pending upload survives an app kill, and
 `MovesJournal.flush()` is awaited before enqueue to beat the journal's async
 persistence. Inbound `Journal` records are deliberately ignored (`case
 "Journal": break`) — 2b fetches them on demand instead of applying peers' logs.
 
 `JournalCodec` carries the mark as the single lossless `markCode` (matching
 `JournalEntity`), not the `Moves` two-bool flattening, and decodes optionals
 leniently for forward-compat. Key files: `Persistence/Journal.swift`,
 `Sync/RecordSerializer.swift`, `Sync/RecordBuilder.swift`, `Sync/SyncEngine.swift`
 (`enqueueJournalUpload`), `Persistence/GameStore.swift`, `Services/AppServices.swift`.
 
 CloudKit schema: the `Journal` record type (`authorID` String, `deviceID`
 String, `updatedAt` Date/Time, `entries` Asset) was added manually and deployed
 to Development and Production on 2026-05-30. No new zone.
 
 ## Phase 2b — cross-device replay data layer (built)
 
 The read side of replay. `SyncEngine.fetchReplay(forGameID:)` (in
 `Sync/CloudQuery.swift`) runs two zone-scoped `CKQuery`s against the finished
 game's zone — one for `Journal` records (decoding each `entries` asset via
 `JournalCodec`) and one for `Moves` records (keys only) — and returns a
 `JournalReplayFetch { journals, expectedDevices }`. It's a plain query, so it
 never disturbs the sync engine's change token; inbound `Journal` records stay
 ignored in the delegate path.
 
 `Persistence/JournalReplay.swift` holds the pure, unit-tested core:
 - `ReplayTimeline(merging:)` flattens every device's log and orders it by
   `timestamp` (ties break on `actingAuthorID` then `seq`, so fetch order can't
   change the result). `state(through:)` folds the first *n* steps last-write-
   per-cell into `[GridPosition: JournalCellState]`. Forward replay needs only
   each entry's after-state, so device-local `seq`/`prevSeqAtCell` are unused;
   undo/check/reveal rows replay naturally as timestamped restores.
 - `ReplayAssembler.assemble(fetch:localKey:localEntries:)` overlays this
   device's *live* log over any uploaded copy of itself, then enforces **strict
   completeness**: `.ready(timeline)` only when a journal is present for every
   expected device, else `.waiting(missing:)`. `AppServices.loadReplay(gameID:)`
   composes `fetchReplay` + `GameStore.localReplaySource` + the assembler and
   maps an unreachable zone to `.unavailable`.
 
 **Strict completeness needs late devices to upload.** Completion learned purely
 via sync used to set `completedAt` without uploading the local journal, so a
 device away at finish time would block replay forever. `applyGameRecord` now
 signals a not-completed → completed transition (`onCompletedTransition`), and
 both inbound apply paths enqueue this device's journal upload — so any
 contributing device that ever syncs the finished game converges. Residual: a
 device that wrote cells and is then permanently gone keeps replay `.waiting`
 indefinitely (accepted trade-off; a "replay anyway" affordance could relax it).
 
 ## Remaining work
 
 - **Phase 3 — scrubber UI.** A scrubber inside the finish banner (above the
   victory image + scoreboard in `SuccessPanel`), head starting hard-right at the
   finished grid and dragging left to rewind. Drives the main `GridView` from
   `ReplayTimeline.state(through:)`; disabled with a "waiting to sync history"
   overlay while `loadReplay` returns `.waiting`.
 - **Completion lockout.** Gate undo/redo off once the game's `completedAt` is
   set, so a finished game can't be rewound.