ttrpg-initiative-tracker/docs/LOG_REDESIGN_PLAN.md

Log System Redesign Plan

Status: DRAFT — not started Branch: feat-turn-writes-logs Goal: Lean mutation deltas. Kill bloated payload/undo duplication.

Problem

Current events = 10-16KB each. add_participant row = 16KB to say "Fighter added, init 22." Root cause: full participant roster stored 3x (payload + undo_payload.updates + undo_payload.redo).

DB: 2486 docs, most bloated. Replay trace 1.6-5.5MB for ~250 steps.

Old log (pre-refactor) = message string + small undo object. Proven worked for undo/redo + viewer. Just wanted MORE STRUCTURE, not MORE DATA. Overbuilt instead.

Intention

Each event = mutation delta + lean snapshot. Structured for filter/group/analyzer. No roster arrays.

Canonical lean event shape

{
  id, ts, type,                    // identity + filter key
  message,                         // human text (viewer displays)
  encounterId, encounterName,      // which encounter
  participantId, participantName,  // who (nullable: pause/nextTurn have none)
  // type-specific scalar delta (one of these clusters per type):
  //   add:        { init, maxHp, type: 'character'|'monster' }
  //   remove:     { dead: bool }
  //   damage/heal:{ amount }
  //   condition:  { condition }
  //   toggleActive:{ revive: bool }
  //   reorder:    { draggedId, targetId }
  //   update:     { changedFields: ['notes', ...] }
  //   nextTurn:   (none — snapshot carries new round/pointer)
  //   pause/resume/start/end: (none)
  snapshot: {                      // lean, ALREADY GOOD — keep as-is
    round, currentTurnParticipantId, turnOrderIds, activeIds
  },
  undo: <type-specific inverse, id-based>  // minimal
}

Undo inverses (id-based, minimal)

type	undo
add_participant	{ participantId } → removeParticipant by id
remove_participant	full participant obj (must restore — only place full obj needed)
damage	{ amount: -amount } or heal back
heal	{ amount: -amount } or damage back
condition	{ condition } (toggle is its own inverse)
toggleActive	{ revive: !revive }
reorder	{ draggedId, targetId } (swap back)
update	{ changedFields: [...], oldValues: {...} }
nextTurn	{ currentTurnParticipantId, round } from snapshot delta
pause/resume	toggle
start/end	full prior scalar state

No redo field. Redo = re-apply forward delta from event itself.

No undo_payload wrapper. Just undo object.

4 Consumers

1. Viewer — shows message + type + participantName + undone flag. Legacy logs (no type) display message only.
2. Undo/redo — apply undo inverse by id. Id-based, minimal.
3. Replay — turn.js funcs write own lean events. Trust func return. NO read-back. JSONL trace = lean snapshots + types.
4. Analyzer — reads snapshot sequence + type. Reconstructs roster from event stream (add/remove by id). NO payload arrays needed.

Legacy Support

• Viewer: yes — show old message-only logs, no type parse
• Undo: no — old logs unundoable (acceptable, sit inert)
• Analyzer: best-effort — snapshot may be absent on legacy → skip invariant check for that run

Why Lean

• add_participant 16KB → ~150 bytes
• Replay trace 5.5MB → ~250KB
• Undo still works (proven old log did same)
• Analyzer unaffected (uses snapshot+type, not payload)

Migration Plan

Phase 1: Redesign event writers (shared/turn.js)

• Rewrite buildEntry() to produce lean shape (delta fields per type)
• Rewrite commit() — no patch storage, write lean event
• Per-func: compute minimal delta + inverse from enc before/after
• Drop payload, undo_payload, undo_payload.redo

Phase 2: Update undo executor

• Find undo consumer (App.js applyUndo or similar)
• Switch to id-based inverse application
• Handle each type's undo shape
• Drop transactionalUndo full-patch path if exists

Phase 3: Update replay trace

• replay-combat.js callStep: trust return, snapshot only (no read-back)
• Trace = {step, ts, type, pre:leanSnap, post:leanSnap} — no participant arrays

Phase 4: Update analyzer

• analyze-turns.js already uses snapshot+type only — verify no payload dep
• Reconstruct roster from event stream for skip/double-act checks (id-level)

Phase 5: Legacy compat

• logEvent.js normalizeEvent — lift legacy into lean shape (type='legacy', message only)
• Viewer handles legacy gracefully
• Download = lean events only (legacy excluded or message-only)

Phase 6: Cleanup

• Delete old bloated docs from DB? Or leave (inert, viewer reads message)?
• Verify build CI=true passes
• Verify analyzer clean on fresh replay
• Verify undo works on new events

NOT in scope

• Fixing 5 pre-existing initiative bugs (logged in TODO.md, separate)
• Changing snapshot shape (already lean)
• Changing viewer UI (just data source)

Open Questions

• Undo for remove_participant: must restore full obj (only place full obj needed). Acceptable?
• Should legacy logs be deleted from DB or left inert?
• Download format: lean JSON array (no legacy) — confirm